home *** CD-ROM | disk | FTP | other *** search
/ Libris Britannia 4 / science library(b).zip / science library(b) / DJGPP / QDDVX102.ZIP / contrib / dvx / docs / unix2dvx.doc < prev   
Text File  |  1993-07-15  |  6KB  |  133 lines
  1.  
  2.                         UNIX2DVX                                07/22/92
  3.                         --------
  4.  
  5.         Because of the limit of eight characters on filenames in DOS ( plus  a
  6. dot and a three letter extension), it was necessary to rename some of the header
  7. files when porting the X11R4 toolkit to DOS.  DOS will normally truncate any
  8. characters in excess of the eight character limit, and in some cases this
  9. results in different header files resolving to the same shortened DOS name.
  10. When porting programs from UNIX to DOS, it would be very tedious to manually
  11. alter all the header file names in the source code, so this program was
  12. written to automate the process.
  13.  
  14.         UNIX2DVX consists of the executable (UNIX2DVX.EXE) and two ASCII text files,
  15. changes.txt, and wrapper.txt.  The first text file, changes.txt is a list
  16. of all the header file names which have been changed, and what they have been
  17. changed to.  Any line with an exclamation point (!) as its first character
  18. is ignored as a comment.  The changes are in the format :
  19.  
  20.         oldheadername : newheadername
  21.  
  22. Any whitspace on the line is ignored, and the two header names must be separated
  23. by a colon (:). The header file names must be complete, so to replace any
  24. occurances of X11/IntrinsicI.h, you must specify the following line,
  25.  
  26. X11/IntrinsicI.h : X11/IntrinsI.h
  27.  
  28. The default changes.txt file contains all the changes to the standard X11R4
  29. header files, but it can be altered by the user to include any other header
  30. files they wish.
  31.  
  32.  
  33.         The second file, wrapper.txt, contains the text that will be included
  34. at the point where a header file to be replaced is found. Again, any line
  35. preceded by an exclamation point is ignored as a comment. UNIX2DVX does
  36. not simply do a search and replace on all the listed header files, but
  37. instead inserts the requested text at the required points in the code.
  38. By default, this text inserts the folowing :
  39.  
  40. #ifdef MSDOS
  41. #include "$MSDOSNAME"           /* MTP $DATE $TIME */
  42. #else
  43. #include "$UNIXNAME"
  44. #endif
  45.  
  46.         $MSDOSNAME and $UNIXNAME resolve to the header name to be replaced,
  47. and its new truncated name respectively, and date and time are replaced
  48. by the current date and time extracted from the system. With this configuration,
  49. when compiling under DOS, simply define MSDOS at compile time. This text could
  50. simply be replaced by :
  51.  
  52. #include "$MSDOSNAME"
  53.  
  54. This would result in a straight substitution of the header file names.
  55.  
  56.  
  57.         The executable (HC.EXE) upon startup, first reads in the changes file,
  58. and checks it for simple sytax errors.  This file default may be overridden
  59. by using the parameter -c=xxx.ext.  If no path or drive is specified, the current
  60. directory is first searched, and then the directory of HC.EXE is searched.
  61. If no extension is provided, the default ".TXT" is used.  The next file read
  62. is the wrapper text file.  Again this may be overridden, using the -w=xxx.ext.
  63. The same search conditions apply as to the changes file.
  64.  
  65.         Wild cards are acceptable (*,?) in the input file spec. HC.EXE searches
  66. through the file, looking for #include statements, and then compares their
  67. contents to the list it read in from the changes.txt file.  If it matches one,
  68. it then
  69.         a) Checks to see if it is contained within a conditional
  70.            compiler statement already
  71.         b) Compares the text surrounding the include statement to the
  72.            wrapper insertion text read in from wrapper.txt
  73.  
  74. If both of these check out, it then inserts the appropriate text at that
  75. position. (Note, any comments on the original line will be moved to below the
  76. wrapper text insertion in the processed file)
  77.  
  78.         Because the wrapper text may be changed by the user, trying to decide
  79. if an include has been previously preprocessed became more tricky. I decided
  80. that most people will stick approximately with the original wrapper.txt,
  81. give or take a few comments. It was on this assumption that I do the comparision
  82. between the wrapper text and the lines surrounding the #include in the source
  83. file being preprocessed. I first remove all white space from the line, and
  84. then remove any comments before comparing the lines.
  85.  
  86. When preprocessing is finished, the original file is renamed to a .BAK (in
  87. case you require it). All changes and warnings are written to stdout, and
  88. so may be redirected to a file.
  89.  
  90. Command line switches
  91. ---------------------
  92.  
  93.         (Note :  all switches may begin with either a '/' or a '-',
  94.          they are not case sensitive, and may appear in any position
  95.          and order on the command line)
  96.  
  97.         -?
  98.         -h[elp]
  99.                 Provides a list of all switches and a brief description
  100.                 of each.
  101.  
  102.         -c=xxx.ext
  103.                 Selects new changes file. (discussed above)
  104.  
  105.         -w=xxx.ext
  106.                 Selects new wrapper file. (discussed above)
  107.  
  108.         -l
  109.                 Lists to screen the changes that would be made,
  110.                 does not alter the input file.
  111.  
  112.         -i
  113.                 Ignore Case. This will affect the comparisons
  114.                 between the header files in the source, and the list of files
  115.                 to be replaced in changes.txt (e.g. x11/IntrinsicI.h and
  116.                 X11/IntrinsicI.h will not match normally - they will with
  117.                 this option.) This also affects the comparsion between
  118.                 the wrapper text and the source file.
  119.  
  120.         -nw
  121.                 No Wrapper check. UNIX2DVX will not compare the wrapper text
  122.                 to the lines surrounding the #include in the source, to see if
  123.                 it has been previously preprocessed.
  124.  
  125.         -d=val
  126.                 Set allowed depth of nested ifdefs. Normally, this defaults
  127.                 to zero, meaning if an header file which should be replaced
  128.                 is contained within a conditional statement, it will not be
  129.                 replaced.  In some modules, and header files, this may
  130.                 need to be changed, because the entire code could
  131.                 be contained within an ifdef statement.
  132.  
  133.